<?php
/**
 *
 */
interface Yz_Tree_Element_Interface
{

    /**
     *  add an element to the list of children of this element
     *  must check whether an element with child.id is already present in the tree
     */
    public function addChild(Yz_Tree_Element_Interface $child);

    /**
     *  get the list of children of this element
     *  @return Yz_Array : a copy
     */
    #public function children();

    /**
     *  get the 'depth' of this element; 0 = root
     *
     *      depth == position of this element in path()
     *  @return int
     */
    public function depth();

    /**
     *  alias of children()
     */
    public function children();

    /**
     *  get the ID of the element
     */
    public function id();

    /**
     *  get the value of the element
     */
    public function value();

    /**
     *  test if this element has children
     */
    public function hasChildren();

    /**
     *  get the parent element of this element
     */
    public function parentElement();

    /**
     *  get the list of ancestor nodes, from the root element to this element inclusive
     */
    public function path();

    /**
     *  remove an element from the list of children of this element
     *  also remove the element from the tree it belonged to
     *  Note: to remove an element by id, use unset()
     */
    public function removeChild(Yz_Tree_Element_Interface $child);

    /**
     *  set the value of the element
     */
    public function assignValue($value);

    /**
     *  get the value of the current element (alias of getValue())
     */
    #public function value();

}
